ExpressionΒΆ

An expression is a Lua scriptable node that drives an attribute value. The purpose of expressions is to let user build custom behaviours without the need to write plugins.

Create an expression
  1. Select the node.
  2. Create an expression by holding down when on the button at the right of the attribute in a Properties view, then using 'Create Expression'.

An attribute expression can have optional inputs and outputs. You can create a new input or output at any time.

Add an input/output
  1. Select the expression node by clicking on the '>' button at the right of the attribute or using a Node List view.
  2. Add an input/output by typing its name and selecting its type using widgets of Inputs/Outputs in a Properties view, then clicking on the Add button.

An input/output type can be freely choosen at creation; however, the type can't be changed once the input/output is created. The script should respect the declared input/output type, failure to do so may lead to crashes. For instance, assigning a three float table to a float output is not legal.

Some inputs have predefined types, such as Time, which automatically connects the newly created input to the Time plug of the Document.

Delete an input/output
  1. Select the expression node.
  2. Delete an input or output by clicking on its button in a Properties view.

You can edit the script using Lua code. By default the script set the output 'Out' to 0.

Edit the script
  1. Select the expression node.
  2. Edit the script by clicking on the Script 'Edit' button, then using the text editor.

Whenever an input or the script is modified, it is evaluated and sets its outputs accordingly. Within the context of the script, the inputs and the outputs are accessed directly using their name. For instance, an expression that has two inputs Input1 and Input2 and two outputs Output1 and Output2, a script could be:

local mul = Input1 * Input2
local add = Input1 + Input2
Output1 = mul / add
Output2 = add / mul

Scripts are evaluated within a special sandbox that reflects the global Lua state. The sandbox allows local changes but won't let the internal Lua state to be overriden. All other Lua semantic is kept unchanged. It is also forbidden to change the scene graph within an expression script, such as connecting plugs, changing plugs values and so on. More generally, expression scripts should have no side effect and be reproductible in any circumstances.